Fox's Git Mirrors
docs/en/package-map.md 633735d797cc5f5d48cb2e22e8fd7cd743930daf (633735d7) Text, 13.62 KB
Package map
Overview
Public API lives under T383838pkg/. The daemon and tests import these packages. T383838internal/ holds daemon-specific wiring that is not a stable import path for external modules.
This page maps each package to its responsibility and primary entry points. For recipes, Python migration, and concurrency rules, see API reference.
Core protocol stack
T383838pkg/packet
Wire packet serialization, header types 1 and 2, hashing, receipts.
┌────────────┬─────────────────────────────────────┐
│ Item │ Detail │
├────────────┼─────────────────────────────────────┤
│ Key types │ Packet, PacketReceipt │
│ Constants │ T383838MTU = 500 │
│ Main files │ T383838packet.go, T383838receipt.go, T383838constants.go │
└────────────┴─────────────────────────────────────┘
T383838pkg/identity
Key generation, recall, sign and verify, encrypt and decrypt, ratchets, optional Secret Service persistence.
┌──────────────────┬───────────────────────────────────────────────────────────────────────────────┐
│ Item │ Detail │
├──────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ Key types │ Identity │
│ Hardware signing │ NewIdentityWithSigner, RHB1 descriptor in T383838hardware_bound.go │
│ At-rest store │ T383838pkg/identity/store (file or Freedesktop Secret Service), RSSI markers │
│ Main files │ T383838identity.go, T383838identity_signer.go, T383838hardware_bound.go, T383838known_persist.go, T383838known_… │
└──────────────────┴───────────────────────────────────────────────────────────────────────────────┘
T383838pkg/securemem
Best-effort locked buffers for long-term identity private keys (mlock, wipe on close).
┌────────────┬────────────────────────────────┐
│ Item │ Detail │
├────────────┼────────────────────────────────┤
│ Key types │ Buf │
│ Main files │ T383838buf.go, T383838wipe.go, T383838alloc_unix.go │
└────────────┴────────────────────────────────┘
T383838pkg/cryptography
Single integration point for primitives. See Cryptography.
┌────────────┬─────────────────────────────────────────────────────────┐
│ Item │ Detail │
├────────────┼─────────────────────────────────────────────────────────┤
│ Key types │ CryptoProvider, Ed25519Signer │
│ Extension │ SetProvider, ActiveProvider │
│ Main files │ T383838provider.go, T383838stdlib_provider.go, curve/AES/HKDF helpers │
└────────────┴─────────────────────────────────────────────────────────┘
T383838pkg/destination
Application-facing destinations (SINGLE, GROUP, PLAIN, LINK).
┌────────────┬──────────────────────────────┐
│ Item │ Detail │
├────────────┼──────────────────────────────┤
│ Key types │ Destination, RequestHandler │
│ Main files │ T383838destination.go, T383838constants.go │
└────────────┴──────────────────────────────┘
T383838pkg/announce
Announce construction, signing, handler registration.
┌────────────┬─────────────────────────┐
│ Item │ Detail │
├────────────┼─────────────────────────┤
│ Key types │ Announce, Handler │
│ Main files │ T383838announce.go, T383838handler.go │
└────────────┴─────────────────────────┘
T383838pkg/transport
Routing engine: path table, announces, forwarding, links, persistence.
┌────────────┬────────────────────────────────────────────────────────────────────────┐
│ Item │ Detail │
├────────────┼────────────────────────────────────────────────────────────────────────┤
│ Key types │ Transport, PathInfo │
│ Main files │ T383838transport.go, T383838ingress.go, T383838relay.go, T383838path_selection.go, T383838path_persist.go │
└────────────┴────────────────────────────────────────────────────────────────────────┘
See Transport.
T383838pkg/link
Encrypted bidirectional links, request/response, channel and resource integration.
┌──────────────┬───────────────────────────────────────────────────────────┐
│ Item │ Detail │
├──────────────┼───────────────────────────────────────────────────────────┤
│ Key types │ Link │
│ Entry points │ HandleIncomingLinkRequest, Reestablish, WatchAndReconnect │
│ Main files │ T383838link.go, T383838link_path_recovery.go, T383838reconnect.go │
└──────────────┴───────────────────────────────────────────────────────────┘
T383838pkg/pathfinder
Per-link path lookup table used inside links.
┌───────────┬──────────────────┐
│ Item │ Detail │
├───────────┼──────────────────┤
│ Key types │ PathFinder, Path │
│ Main file │ T383838pathfinder.go │
└───────────┴──────────────────┘
Data transfer and messaging
T383838pkg/channel
Reliable message delivery over a link.
┌────────────┬──────────────────────────┐
│ Item │ Detail │
├────────────┼──────────────────────────┤
│ Key types │ Channel, Envelope │
│ Main files │ T383838channel.go, T383838constants.go │
└────────────┴──────────────────────────┘
T383838pkg/buffer
Stream buffer over channel with bzip2 compression.
┌────────────┬─────────────────────────┐
│ Item │ Detail │
├────────────┼─────────────────────────┤
│ Key types │ Buffer │
│ Main files │ T383838buffer.go, T383838constants.go │
└────────────┴─────────────────────────┘
T383838pkg/resource
Multi-part file transfer, hashmaps, RESOURCE_PRF, bzip2.
┌────────────┬──────────────────────────────────────────────────┐
│ Item │ Detail │
├────────────┼──────────────────────────────────────────────────┤
│ Key types │ Resource, Advertisement │
│ Main files │ T383838resource.go, T383838advertisement.go, T383838bzip2_compress.go │
└────────────┴──────────────────────────────────────────────────┘
Network interfaces
T383838pkg/interfaces
All interface implementations and factory.
┌──────────────┬──────────────────────────────────────────────────────────────────┐
│ Item │ Detail │
├──────────────┼──────────────────────────────────────────────────────────────────┤
│ Key types │ Interface, BaseInterface │
│ Factory │ NewFromConfigWithContext in T383838fromconfig.go │
│ Reconnect │ T383838reconnect.go │
│ Lifecycle │ T383838lifecycle.go (Enable, Disable, Detach) │
│ Go-only QUIC │ T383838quic.go, T383838quic_tls.go (QUICClientInterface / QUICServerInterface) │
└──────────────┴──────────────────────────────────────────────────────────────────┘
See Interfaces.
T383838pkg/ifac
Interface Access Code mask and unmask.
┌───────────┬──────────────────────────┐
│ Item │ Detail │
├───────────┼──────────────────────────┤
│ Key types │ Identity (IFAC identity) │
│ Main file │ T383838ifac.go │
└───────────┴──────────────────────────┘
T383838pkg/i2p
I2P SAM client, destinations, tunnels.
┌────────────┬──────────────────────────────────────────────────┐
│ Item │ Detail │
├────────────┼──────────────────────────────────────────────────┤
│ Key types │ Controller, Destination, Tunnel │
│ Main files │ T383838sam.go, T383838controller.go, T383838destination.go, T383838tunnel.go │
└────────────┴──────────────────────────────────────────────────┘
T383838pkg/backbone
Multiplexed I/O hub for backbone TCP.
┌────────────┬───────────────────────────────────────┐
│ Item │ Detail │
├────────────┼───────────────────────────────────────┤
│ Key types │ Hub, Backend │
│ Backends │ auto, epoll, kqueue, io_uring, go │
│ Main files │ T383838backbone.go, T383838hub.go, platform pollers │
└────────────┴───────────────────────────────────────┘
Node orchestration and embedding
T383838pkg/node
Embedder API: transport plus interfaces plus lifecycle.
┌────────────┬───────────────────────────────────────────────────────────────────┐
│ Item │ Detail │
├────────────┼───────────────────────────────────────────────────────────────────┤
│ Key types │ Node, PauseMode, LinkReconnectOptions │
│ Lifecycle │ OnNetworkAvailable, OnNetworkLost, RefreshPaths, ReloadInterfaces │
│ Main files │ T383838node.go, T383838lifecycle.go, T383838reload.go, T383838wiring.go, T383838netmon.go │
└────────────┴───────────────────────────────────────────────────────────────────┘
T383838pkg/sharedinstance
Python share_instance equivalent.
┌────────────┬────────────────────────────────┐
│ Item │ Detail │
├────────────┼────────────────────────────────┤
│ Key types │ Instance, Hooks │
│ Entry │ T383838Attach(cfg, tr, hooks) │
│ Framing │ SendFramed / RecvFramed │
│ Main files │ T383838instance.go, T383838rpc.go, T383838mpconn.go │
└────────────┴────────────────────────────────┘
T383838pkg/cli
Subcommand dispatch for the unified T383838reticulum-go binary (Main, RunStatus, RunID, RunProbe, RunPath, RunCP, RunPageserver).
┌───────┬──────────────────────────────────────────────────────────────────────────────────────────┐
│ Item │ Detail │
├───────┼──────────────────────────────────────────────────────────────────────────────────────────┤
│ Entry │ T383838Main(opts) from T383838cmd/reticulum-go │
│ Docs │ CLI utilities.
T383838pkg/librns
C ABI facade for in-process embed. Pure Go core. CGO shims in T383838pkg/librns/capi.
┌────────────┬─────────────────────────────────────────────────────────┐
│ Item │ Detail │
├────────────┼─────────────────────────────────────────────────────────┤
│ Header │ T383838include/rns.h │
│ Shared lib │ T383838task build-librns produces T383838bin/librns.so │
│ Smoke │ T383838bindings/c/examples/smoke │
│ Odin │ T383838bindings/odin (T383838task test-odin) │
│ Zig │ T383838bindings/zig (T383838task test-zig) │
│ C++ │ T383838bindings/cpp (T383838task test-cpp) │
│ Main files │ T383838node.go, T383838identity.go, T383838destination.go, T383838link.go, T383838queue.go │
└────────────┴─────────────────────────────────────────────────────────┘
See librns.
T383838bindings/odin
Idiomatic Odin package over T383838librns.so. Not a Go import path. Use T383838-collection:rns=bindings/odin and T383838import rns "rns:rns".
┌──────────┬──────────────────────────────────────────────┐
│ Item │ Detail │
├──────────┼──────────────────────────────────────────────┤
│ Package │ T383838bindings/odin/rns │
│ Tests │ T383838bindings/odin/tests │
│ Build │ T383838task test-odin or T383838make -C bindings/odin test │
│ Platform │ Linux (links T383838system:rns) │
└──────────┴──────────────────────────────────────────────┘
See librns.
T383838bindings/zig
Idiomatic Zig package over T383838librns.so. Not a Go import path. Depend on T383838bindings/zig from T383838build.zig.zon and T383838@import("rns").
┌──────────┬────────────────────────────────────────────┐
│ Item │ Detail │
├──────────┼────────────────────────────────────────────┤
│ Package │ T383838bindings/zig (module rns) │
│ Tests │ T383838bindings/zig/tests │
│ Build │ T383838task test-zig or T383838make -C bindings/zig test │
│ Platform │ Linux (links T383838-lrns) │
└──────────┴────────────────────────────────────────────┘
See librns.
T383838bindings/cpp
Idiomatic C++17 RAII package over T383838librns.so. Not a Go import path. Include T383838rns/rns.hpp and link librns plus the event trampoline (or the rns_cpp CMake target).
┌──────────┬────────────────────────────────────────────┐
│ Item │ Detail │
├──────────┼────────────────────────────────────────────┤
│ Package │ T383838bindings/cpp/include/rns │
│ Tests │ T383838bindings/cpp/tests │
│ Build │ T383838task test-cpp or T383838make -C bindings/cpp test │
│ Platform │ Linux (links T383838-lrns) │
│ Standard │ C++17 and up │
└──────────┴────────────────────────────────────────────┘
See librns.
T383838bindings/dart
Dart package rns_control with librns FFI (T383838ffi.dart) and a Control API client. Path dependency for Flutter apps.
┌───────────┬─────────────────────────────────────────────────────────────────────────────────┐
│ Item │ Detail │
├───────────┼─────────────────────────────────────────────────────────────────────────────────┤
│ Package │ T383838bindings/dart (T383838name: rns_control) │
│ FFI │ Linux, Android, Windows via librns (T383838package:rns_control/ffi.dart) │
│ Tests │ T383838dart test / T383838task test-dart │
│ Platforms │ Flutter mobile and desktop (events need T383838dart:io). FFI needs shipped native libs │
└───────────┴─────────────────────────────────────────────────────────────────────────────────┘
See Control API.
Discovery and policy
T383838pkg/discovery
rnstransport wire constants, LXStamper, msgpack layouts.
┌────────────┬──────────────────────────────────────┐
│ Item │ Detail │
├────────────┼──────────────────────────────────────┤
│ Key types │ InterfaceDiscovery │
│ Main files │ T383838discovery.go, T383838interface_discovery.go │
└────────────┴──────────────────────────────────────┘
T383838pkg/blackhole
Blackhole table semantics, merge, announce filtering.
┌───────────┬──────────────┐
│ Item │ Detail │
├───────────┼──────────────┤
│ Key types │ Table, Entry │
│ Main file │ T383838blackhole.go │
└───────────┴──────────────┘
T383838pkg/rate
Token-bucket limiter, ingress and egress announce controls.
┌───────────┬─────────────────────────┐
│ Item │ Detail │
├───────────┼─────────────────────────┤
│ Key types │ Limiter, IngressControl │
│ Main file │ T383838rate.go │
└───────────┴─────────────────────────┘
Configuration and shared types
T383838pkg/reticulumconfig
Canonical INI parser and writer.
┌───────────┬──────────────────────────────────────────────────────────────────┐
│ Item │ Detail │
├───────────┼──────────────────────────────────────────────────────────────────┤
│ Functions │ LoadConfig, SaveConfig, DefaultConfig, InitConfig, GetConfigPath │
│ Main file │ T383838config.go │
└───────────┴──────────────────────────────────────────────────────────────────┘
T383838pkg/common
Shared config structs, path types, IFAC helpers, persistence utilities.
┌────────────┬────────────────────────────────────────────────────┐
│ Item │ Detail │
├────────────┼────────────────────────────────────────────────────┤
│ Key types │ ReticulumConfig, InterfaceConfig, Path │
│ Main files │ T383838types.go, T383838config.go, T383838interfaces.go, T383838persistence.go │
└────────────┴────────────────────────────────────────────────────┘
T383838pkg/config (legacy)
Older standalone config struct. New code should use T383838pkg/reticulumconfig.
Security and operations
T383838pkg/sandbox
Post-startup OS restrictions.
┌────────────┬─────────────────────────────────────────────────────────┐
│ Item │ Detail │
├────────────┼─────────────────────────────────────────────────────────┤
│ Entry │ T383838Apply(cfg), T383838SetExecRlimits, T383838StartLimited, T383838OutputLimited │
│ Main files │ T383838sandbox.go, T383838paths.go, platform-specific files │
└────────────┴─────────────────────────────────────────────────────────┘
T383838pkg/debug
Structured logging with debug levels 1 through 7.
┌───────────┬──────────────────────────┐
│ Item │ Detail │
├───────────┼──────────────────────────┤
│ Functions │ Init, Log, SetDebugLevel │
│ Main file │ T383838debug.go │
└───────────┴──────────────────────────┘
Utilities
T383838pkg/resolver
Deterministic identity resolution from a full name string (SHA-256).
┌───────────┬─────────────┐
│ Item │ Detail │
├───────────┼─────────────┤
│ Key type │ Resolver │
│ Main file │ T383838resolver.go │
└───────────┴─────────────┘
Internal packages (not stable for importers)
T383838internal/config
Re-exports T383838pkg/reticulumconfig for the daemon.
T383838internal/storage
Filesystem persistence under T383838~/.reticulum-go/storage/.
┌────────────┬───────────────────────┐
│ Item │ Detail │
├────────────┼───────────────────────┤
│ Key type │ Manager │
│ Main files │ T383838manager.go, T383838atomic.go │
└────────────┴───────────────────────┘
Command binaries
┌───────────────────────────┬──────────────┬───────────────────────────────────────────────────────┐
│ Path │ Binary │ Role │
├───────────────────────────┼──────────────┼───────────────────────────────────────────────────────┤
│ T383838cmd/reticulum-go │ T383838reticulum-go │ Daemon and tools (status, id, probe, path, cp, pages… │
│ T383838cmd/rgostatus … T383838cmd/rgocp │ (wrappers) │ Call into T383838pkg/cli for compatibility with old build s… │
│ T383838cmd/reticulum-wasm │ WASM module │ Browser entry │
└───────────────────────────┴──────────────┴───────────────────────────────────────────────────────┘
CLI dispatch lives in T383838pkg/cli. Pageserver logic lives in T383838pkg/pageserver.
Suggested import paths for applications
┌──────────────────────────────┬──────────────────────────────────────────────────────────────┐
│ Task │ Packages │
├──────────────────────────────┼──────────────────────────────────────────────────────────────┤
│ Embed full node │ T383838pkg/node, T383838pkg/reticulumconfig, T383838pkg/destination, T383838pkg/identity │
│ Embed from C / FFI │ T383838pkg/librns (or link T383838librns.so + T383838include/rns.h) │
│ Embed from Odin │ T383838bindings/odin (T383838import rns "rns:rns", link T383838librns.so) │
│ Flutter / Dart FFI │ T383838bindings/dart (T383838package:rns_control/ffi.dart) │
│ Flutter / Dart Control API │ T383838bindings/dart (T383838package:rns_control) │
│ Low-level transport only │ T383838pkg/transport, T383838pkg/interfaces, T383838pkg/packet │
│ Crypto only │ T383838pkg/cryptography, T383838pkg/identity │
│ Browser │ T383838pkg/wasm (compiled), WebSocket interface │
│ Out-of-process non-Go client │ Control API (T383838pkg/controlapi on the daemon) │
└──────────────────────────────┴──────────────────────────────────────────────────────────────┘
Do not import T383838internal/ from outside this module.
Related documents
Served by rngit 1.5.2 - Generated in 0.03s